home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / src / linux-headers-2.6.28-15 / include / linux / usb / composite.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-12-24  |  14.3 KB  |  346 lines
  1. /*
  2.  * composite.h -- framework for usb gadgets which are composite devices
  3.  *
  4.  * Copyright (C) 2006-2008 David Brownell
  5.  *
  6.  * This program is free software; you can redistribute it and/or modify
  7.  * it under the terms of the GNU General Public License as published by
  8.  * the Free Software Foundation; either version 2 of the License, or
  9.  * (at your option) any later version.
  10.  *
  11.  * This program is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; if not, write to the Free Software
  18.  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19.  */
  20.  
  21. #ifndef    __LINUX_USB_COMPOSITE_H
  22. #define    __LINUX_USB_COMPOSITE_H
  23.  
  24. /*
  25.  * This framework is an optional layer on top of the USB Gadget interface,
  26.  * making it easier to build (a) Composite devices, supporting multiple
  27.  * functions within any single configuration, and (b) Multi-configuration
  28.  * devices, also supporting multiple functions but without necessarily
  29.  * having more than one function per configuration.
  30.  *
  31.  * Example:  a device with a single configuration supporting both network
  32.  * link and mass storage functions is a composite device.  Those functions
  33.  * might alternatively be packaged in individual configurations, but in
  34.  * the composite model the host can use both functions at the same time.
  35.  */
  36.  
  37. #include <linux/usb/ch9.h>
  38. #include <linux/usb/gadget.h>
  39.  
  40.  
  41. struct usb_configuration;
  42.  
  43. /**
  44.  * struct usb_function - describes one function of a configuration
  45.  * @name: For diagnostics, identifies the function.
  46.  * @strings: tables of strings, keyed by identifiers assigned during bind()
  47.  *    and by language IDs provided in control requests
  48.  * @descriptors: Table of full (or low) speed descriptors, using interface and
  49.  *    string identifiers assigned during @bind().  If this pointer is null,
  50.  *    the function will not be available at full speed (or at low speed).
  51.  * @hs_descriptors: Table of high speed descriptors, using interface and
  52.  *    string identifiers assigned during @bind().  If this pointer is null,
  53.  *    the function will not be available at high speed.
  54.  * @config: assigned when @usb_add_function() is called; this is the
  55.  *    configuration with which this function is associated.
  56.  * @bind: Before the gadget can register, all of its functions bind() to the
  57.  *    available resources including string and interface identifiers used
  58.  *    in interface or class descriptors; endpoints; I/O buffers; and so on.
  59.  * @unbind: Reverses @bind; called as a side effect of unregistering the
  60.  *    driver which added this function.
  61.  * @set_alt: (REQUIRED) Reconfigures altsettings; function drivers may
  62.  *    initialize usb_ep.driver data at this time (when it is used).
  63.  *    Note that setting an interface to its current altsetting resets
  64.  *    interface state, and that all interfaces have a disabled state.
  65.  * @get_alt: Returns the active altsetting.  If this is not provided,
  66.  *    then only altsetting zero is supported.
  67.  * @disable: (REQUIRED) Indicates the function should be disabled.  Reasons
  68.  *    include host resetting or reconfiguring the gadget, and disconnection.
  69.  * @setup: Used for interface-specific control requests.
  70.  * @suspend: Notifies functions when the host stops sending USB traffic.
  71.  * @resume: Notifies functions when the host restarts USB traffic.
  72.  *
  73.  * A single USB function uses one or more interfaces, and should in most
  74.  * cases support operation at both full and high speeds.  Each function is
  75.  * associated by @usb_add_function() with a one configuration; that function
  76.  * causes @bind() to be called so resources can be allocated as part of
  77.  * setting up a gadget driver.  Those resources include endpoints, which
  78.  * should be allocated using @usb_ep_autoconfig().
  79.  *
  80.  * To support dual speed operation, a function driver provides descriptors
  81.  * for both high and full speed operation.  Except in rare cases that don't
  82.  * involve bulk endpoints, each speed needs different endpoint descriptors.
  83.  *
  84.  * Function drivers choose their own strategies for managing instance data.
  85.  * The simplest strategy just declares it "static', which means the function
  86.  * can only be activated once.  If the function needs to be exposed in more
  87.  * than one configuration at a given speed, it needs to support multiple
  88.  * usb_function structures (one for each configuration).
  89.  *
  90.  * A more complex strategy might encapsulate a @usb_function structure inside
  91.  * a driver-specific instance structure to allows multiple activations.  An
  92.  * example of multiple activations might be a CDC ACM function that supports
  93.  * two or more distinct instances within the same configuration, providing
  94.  * several independent logical data links to a USB host.
  95.  */
  96. struct usb_function {
  97.     const char            *name;
  98.     struct usb_gadget_strings    **strings;
  99.     struct usb_descriptor_header    **descriptors;
  100.     struct usb_descriptor_header    **hs_descriptors;
  101.  
  102.     struct usb_configuration    *config;
  103.  
  104.     /* REVISIT:  bind() functions can be marked __init, which
  105.      * makes trouble for section mismatch analysis.  See if
  106.      * we can't restructure things to avoid mismatching.
  107.      * Related:  unbind() may kfree() but bind() won't...
  108.      */
  109.  
  110.     /* configuration management:  bind/unbind */
  111.     int            (*bind)(struct usb_configuration *,
  112.                     struct usb_function *);
  113.     void            (*unbind)(struct usb_configuration *,
  114.                     struct usb_function *);
  115.  
  116.     /* runtime state management */
  117.     int            (*set_alt)(struct usb_function *,
  118.                     unsigned interface, unsigned alt);
  119.     int            (*get_alt)(struct usb_function *,
  120.                     unsigned interface);
  121.     void            (*disable)(struct usb_function *);
  122.     int            (*setup)(struct usb_function *,
  123.                     const struct usb_ctrlrequest *);
  124.     void            (*suspend)(struct usb_function *);
  125.     void            (*resume)(struct usb_function *);
  126.  
  127.     /* internals */
  128.     struct list_head        list;
  129. };
  130.  
  131. int usb_add_function(struct usb_configuration *, struct usb_function *);
  132.  
  133. int usb_function_deactivate(struct usb_function *);
  134. int usb_function_activate(struct usb_function *);
  135.  
  136. int usb_interface_id(struct usb_configuration *, struct usb_function *);
  137.  
  138. /**
  139.  * ep_choose - select descriptor endpoint at current device speed
  140.  * @g: gadget, connected and running at some speed
  141.  * @hs: descriptor to use for high speed operation
  142.  * @fs: descriptor to use for full or low speed operation
  143.  */
  144. static inline struct usb_endpoint_descriptor *
  145. ep_choose(struct usb_gadget *g, struct usb_endpoint_descriptor *hs,
  146.         struct usb_endpoint_descriptor *fs)
  147. {
  148.     if (gadget_is_dualspeed(g) && g->speed == USB_SPEED_HIGH)
  149.         return hs;
  150.     return fs;
  151. }
  152.  
  153. #define    MAX_CONFIG_INTERFACES        16    /* arbitrary; max 255 */
  154.  
  155. /**
  156.  * struct usb_configuration - represents one gadget configuration
  157.  * @label: For diagnostics, describes the configuration.
  158.  * @strings: Tables of strings, keyed by identifiers assigned during @bind()
  159.  *    and by language IDs provided in control requests.
  160.  * @descriptors: Table of descriptors preceding all function descriptors.
  161.  *    Examples include OTG and vendor-specific descriptors.
  162.  * @bind: Called from @usb_add_config() to allocate resources unique to this
  163.  *    configuration and to call @usb_add_function() for each function used.
  164.  * @unbind: Reverses @bind; called as a side effect of unregistering the
  165.  *    driver which added this configuration.
  166.  * @setup: Used to delegate control requests that aren't handled by standard
  167.  *    device infrastructure or directed at a specific interface.
  168.  * @bConfigurationValue: Copied into configuration descriptor.
  169.  * @iConfiguration: Copied into configuration descriptor.
  170.  * @bmAttributes: Copied into configuration descriptor.
  171.  * @bMaxPower: Copied into configuration descriptor.
  172.  * @cdev: assigned by @usb_add_config() before calling @bind(); this is
  173.  *    the device associated with this configuration.
  174.  *
  175.  * Configurations are building blocks for gadget drivers structured around
  176.  * function drivers.  Simple USB gadgets require only one function and one
  177.  * configuration, and handle dual-speed hardware by always providing the same
  178.  * functionality.  Slightly more complex gadgets may have more than one
  179.  * single-function configuration at a given speed; or have configurations
  180.  * that only work at one speed.
  181.  *
  182.  * Composite devices are, by definition, ones with configurations which
  183.  * include more than one function.
  184.  *
  185.  * The lifecycle of a usb_configuration includes allocation, initialization
  186.  * of the fields described above, and calling @usb_add_config() to set up
  187.  * internal data and bind it to a specific device.  The configuration's
  188.  * @bind() method is then used to initialize all the functions and then
  189.  * call @usb_add_function() for them.
  190.  *
  191.  * Those functions would normally be independant of each other, but that's
  192.  * not mandatory.  CDC WMC devices are an example where functions often
  193.  * depend on other functions, with some functions subsidiary to others.
  194.  * Such interdependency may be managed in any way, so long as all of the
  195.  * descriptors complete by the time the composite driver returns from
  196.  * its bind() routine.
  197.  */
  198. struct usb_configuration {
  199.     const char            *label;
  200.     struct usb_gadget_strings    **strings;
  201.     const struct usb_descriptor_header **descriptors;
  202.  
  203.     /* REVISIT:  bind() functions can be marked __init, which
  204.      * makes trouble for section mismatch analysis.  See if
  205.      * we can't restructure things to avoid mismatching...
  206.      */
  207.  
  208.     /* configuration management:  bind/unbind */
  209.     int            (*bind)(struct usb_configuration *);
  210.     void            (*unbind)(struct usb_configuration *);
  211.     int            (*setup)(struct usb_configuration *,
  212.                     const struct usb_ctrlrequest *);
  213.  
  214.     /* fields in the config descriptor */
  215.     u8            bConfigurationValue;
  216.     u8            iConfiguration;
  217.     u8            bmAttributes;
  218.     u8            bMaxPower;
  219.  
  220.     struct usb_composite_dev    *cdev;
  221.  
  222.     /* internals */
  223.     struct list_head    list;
  224.     struct list_head    functions;
  225.     u8            next_interface_id;
  226.     unsigned        highspeed:1;
  227.     unsigned        fullspeed:1;
  228.     struct usb_function    *interface[MAX_CONFIG_INTERFACES];
  229. };
  230.  
  231. int usb_add_config(struct usb_composite_dev *,
  232.         struct usb_configuration *);
  233.  
  234. /**
  235.  * struct usb_composite_driver - groups configurations into a gadget
  236.  * @name: For diagnostics, identifies the driver.
  237.  * @dev: Template descriptor for the device, including default device
  238.  *    identifiers.
  239.  * @strings: tables of strings, keyed by identifiers assigned during bind()
  240.  *    and language IDs provided in control requests
  241.  * @bind: (REQUIRED) Used to allocate resources that are shared across the
  242.  *    whole device, such as string IDs, and add its configurations using
  243.  *    @usb_add_config().  This may fail by returning a negative errno
  244.  *    value; it should return zero on successful initialization.
  245.  * @unbind: Reverses @bind(); called as a side effect of unregistering
  246.  *    this driver.
  247.  *
  248.  * Devices default to reporting self powered operation.  Devices which rely
  249.  * on bus powered operation should report this in their @bind() method.
  250.  *
  251.  * Before returning from @bind, various fields in the template descriptor
  252.  * may be overridden.  These include the idVendor/idProduct/bcdDevice values
  253.  * normally to bind the appropriate host side driver, and the three strings
  254.  * (iManufacturer, iProduct, iSerialNumber) normally used to provide user
  255.  * meaningful device identifiers.  (The strings will not be defined unless
  256.  * they are defined in @dev and @strings.)  The correct ep0 maxpacket size
  257.  * is also reported, as defined by the underlying controller driver.
  258.  */
  259. struct usb_composite_driver {
  260.     const char                *name;
  261.     const struct usb_device_descriptor    *dev;
  262.     struct usb_gadget_strings        **strings;
  263.  
  264.     /* REVISIT:  bind() functions can be marked __init, which
  265.      * makes trouble for section mismatch analysis.  See if
  266.      * we can't restructure things to avoid mismatching...
  267.      */
  268.  
  269.     int            (*bind)(struct usb_composite_dev *);
  270.     int            (*unbind)(struct usb_composite_dev *);
  271. };
  272.  
  273. extern int usb_composite_register(struct usb_composite_driver *);
  274. extern void usb_composite_unregister(struct usb_composite_driver *);
  275.  
  276.  
  277. /**
  278.  * struct usb_composite_device - represents one composite usb gadget
  279.  * @gadget: read-only, abstracts the gadget's usb peripheral controller
  280.  * @req: used for control responses; buffer is pre-allocated
  281.  * @bufsiz: size of buffer pre-allocated in @req
  282.  * @config: the currently active configuration
  283.  *
  284.  * One of these devices is allocated and initialized before the
  285.  * associated device driver's bind() is called.
  286.  *
  287.  * OPEN ISSUE:  it appears that some WUSB devices will need to be
  288.  * built by combining a normal (wired) gadget with a wireless one.
  289.  * This revision of the gadget framework should probably try to make
  290.  * sure doing that won't hurt too much.
  291.  *
  292.  * One notion for how to handle Wireless USB devices involves:
  293.  * (a) a second gadget here, discovery mechanism TBD, but likely
  294.  *     needing separate "register/unregister WUSB gadget" calls;
  295.  * (b) updates to usb_gadget to include flags "is it wireless",
  296.  *     "is it wired", plus (presumably in a wrapper structure)
  297.  *     bandgroup and PHY info;
  298.  * (c) presumably a wireless_ep wrapping a usb_ep, and reporting
  299.  *     wireless-specific parameters like maxburst and maxsequence;
  300.  * (d) configurations that are specific to wireless links;
  301.  * (e) function drivers that understand wireless configs and will
  302.  *     support wireless for (additional) function instances;
  303.  * (f) a function to support association setup (like CBAF), not
  304.  *     necessarily requiring a wireless adapter;
  305.  * (g) composite device setup that can create one or more wireless
  306.  *     configs, including appropriate association setup support;
  307.  * (h) more, TBD.
  308.  */
  309. struct usb_composite_dev {
  310.     struct usb_gadget        *gadget;
  311.     struct usb_request        *req;
  312.     unsigned            bufsiz;
  313.  
  314.     struct usb_configuration    *config;
  315.  
  316.     /* internals */
  317.     struct usb_device_descriptor    desc;
  318.     struct list_head        configs;
  319.     struct usb_composite_driver    *driver;
  320.     u8                next_string_id;
  321.  
  322.     /* the gadget driver won't enable the data pullup
  323.      * while the deactivation count is nonzero.
  324.      */
  325.     unsigned            deactivations;
  326.  
  327.     /* protects at least deactivation count */
  328.     spinlock_t            lock;
  329. };
  330.  
  331. extern int usb_string_id(struct usb_composite_dev *c);
  332.  
  333. /* messaging utils */
  334. #define DBG(d, fmt, args...) \
  335.     dev_dbg(&(d)->gadget->dev , fmt , ## args)
  336. #define VDBG(d, fmt, args...) \
  337.     dev_vdbg(&(d)->gadget->dev , fmt , ## args)
  338. #define ERROR(d, fmt, args...) \
  339.     dev_err(&(d)->gadget->dev , fmt , ## args)
  340. #define WARNING(d, fmt, args...) \
  341.     dev_warn(&(d)->gadget->dev , fmt , ## args)
  342. #define INFO(d, fmt, args...) \
  343.     dev_info(&(d)->gadget->dev , fmt , ## args)
  344.  
  345. #endif    /* __LINUX_USB_COMPOSITE_H */
  346.